Acorn RISC PD-CD 1

home *** CD-ROM | disk | FTP | other *** search

/ Acorn RISC PD-CD 1 / Acorn RISC PD-CD 1.iso / utilities / _graphics / graphics / _drawlots / interhelp < prev

Wrap

Text File | 1992-06-06 | 21.7 KB | 620 lines

Interface 2.00 © Software Interrupt 1990 See notes at end for update info...... This manual and software is public domain. It may be copied and distributed freely as long as: It is not separated from the documentation (except for commercial use) The module is not tampered with You do not claim that you have written the module Do not use any of the code contained in this module in your own code If you wish to use this in a commercial product please contact me so that I can make sure you have the latest release, please send a disk. In no circumstances shall the author be liable for any damage, loss of profits, time or data or any indirect or consequential loss rising out of the use of this software or inability to use this software. Contacts: Arcade BBS (081 654 2212) The World Of Cryton (0749 679794) All mail on the above Bulletin Bords should be mailed to JICK **************** Introduction *********************************************** Interface is a small module that allows application programmers to implement a colourful and pleasant graphical user interface. Interface provides many more functions that allows you to change the pointer shape easily and to interface with the !Help or !Spy application. The Interface module provides functions to improve the friendliness and appearance of the application. The application should still operate as stated in the Acorn guidelines in the Programmers Reference Manuals. The module implements a number of SWIs which are described further in this manual, these SWI calls can be called from any language. Most of the functions provided are specified in the icons validation string, and so no complex programming is needed to make the application look good. This guide tells you how to fully implement the features of Interface. It is split into the follow sections: The first section explains the validation strings options provided by Interface. The next section gives details of the SWI calls provided. The remaining section covers hints and tips on programming. **************** Technical details ****************************************** An indirected text icon can have a validation string which is used to pass further information to the WIMP, such as what border type the icon has and also what pointer, if any should be displayed whilst over this icon. The syntax of a validation string is: validation string ::- command {;command}* command ::- (b | z) border-type {border-spec} | r on/off-type {,icon-number}* | u on/off-type {,icon-number}* | p text-string {,x} {,y} | i text-string | k key-code border-spec ::- {,button-slabbing-mask} {,slabbing-time} {,colour}* The parameters above are described under the relevant validation command. In simple terms, a validation string consists of a series of 'commands', each starting with a single letter and seperated from the following command by a semi-colon. {}* means zero or more of the thing inside the {}. The following commands are available with the Interface module. These commands are provided in addition to the standard Wimp validation strings. I suggest that you edit the !FormEd program to allow you to enter larger validation strings, otherwise when entering a help command you will only be allowed a maximum of 80 characters. The (B)order command tells Interface which border to use when rendering an icon. The border types available at present are : border type 0, this is a single border used mainly for headings and action icons. The icon will slab inwards if the user clicks a button whilst the pointer is over the icon providing it is not setup to ignore mouse clicks. border type 1, this is a double border and should be used to group together icons that perform an operation. border type 2, this is a triple border and should be used on the default action button. The icon will slab inwards when the user clicks a button whilst the pointer is over this icon providing it is not setup to ignore mouse clicks. border type 3, this is a wide inverted border and should be used on writable icons. This border type is usually used in-conjunction with the writable pointer. border type 4, this is an inverted version of border type 0 border type 5, this is a double wide border as used by acorn in ros 3 border type 6, etched in border border type 7, similar to border type 0, thinner in mode 20 The second optional parameter is the button slabbing mask, this states whether the icon should be slabbed until the button is released. The values contained in this parameter can be from 0 to 7. The button slabbing mask can be calculated in the following way: Value Button Meaning 1 Adjust slab icon until adjust is released 2 Menu slab icon until menu is released 4 Select slab icon until select is released The button slabbing mask can then be calculated by adding together the required button values. The button slabbing time is the minimum time that the icon will be slabbed for, the default time is for 15cs. This value is a decimal number in centi-seconds. The colours are specified in the following order: {,border colour1} {,border colour2} {,slabbing out colour} {,slabbing in colour} {,inner channel colour} These colours can be any valid WIMP colour in the range of 0 to 15, the default selection is 4, 0, 1, 14, 12. The (R)adio command specified in the validation string is used to set the state of other radio button type icons. The R command is followed by a decimal number in the range 0 to 2, the action that these perform is: Radio type Operation 0 this has the effect of switching off the specified icon(s). 1 this has the effect of switching on the specified icon(s). 2 this has the effect of toggling the icons current state. This command is then followed by the numbers of the icons you wish to alter, these should be separated by commas. This command may be specified more than once in a validation string, for example to switch icons 1 & 2 off, 3 & 4 on and toggle the state of icons 5 & 6 you could use the following validation string R0,1,2;R1,3,4;R2,5,6 The (U)nselectable command in the validation string has the effect of shading the icon grey so that it cannot be selected by the user. It is followed by a decimal number in the range 0 to 2, the action that these is described above in the radio command. This command is then followed by the numbers of the icons you wish to alter, these should be separated by commas. This command may be specified more than once in a validation string, for example to shade icons 1 & 2, un-shade 3 & 4 and toggle the state of icons 5 & 6 you could use the following validation string U0,1,2;U1,3,4;U2,5,6 The (P)ointer command is used to define a pointer to be displayed when the pointer is over that icon. The first parameter is a sprite name to use for the pointer, this should be no longer than 12 characters and should be present in the WIMP sprite pool. The optional parameters specify the x and y offsets to the active point in the sprite, these should be specified in pixels. The (I)nformation command is used to define a message to be sent to the interactive help application when the pointer is over the icon. If you wish to use a semi-colon then you must place two next to each other. The maximum length of the help message is 235 characters. The Interface module will change to the specified pointer when the mouse pointer is over the icon/workarea, if no pointer is specified then the pointer will default to shape one (the default arrow shape). There are 5 pointer shapes designed in the sprite file in the !Interface directory, these are: ptr_write - this pointer should be used on writable icons, the suggested active point is at coordinates x = 4, y = 4. ptr_menu - this pointer is used where a menu can be activated by pressing the menu button over the icon. This stops the user having to search all over the window to find where the menu is. The suggested active point is x = 6, y = 5. ptr_direct - this pointer is used where an object may be re-sized, the suggested active point is at x = 13, y = 7. ptr_hand - this pointer is used where and icon may be dragged. It is usually set on the workarea, but it can be used on any icon (the save file icon looks great when using it), its suggested active point is at x = 12, y = 8. ptr_cross - this pointer is used as a crosshair, it is the same as the one used in the Draw application. This icon gives the user a precise point when working with line drawings, its suggested active point is at x = 13, y = 7. You may also design your own pointers, which should be loaded into the WIMP sprite pool. There are a few points that you should note when designing pointers these are : Pointer sprite names should have the form ptr_XXXXX, although this is not compulsory it helps so that you do not get confused with pointers and normal sprites. Do not use logical colour 2 in the pointer sprites, as this is unavailable in very high resolution modes. The pointers used should only be valid in your application, so you must not mask out the Pointer_Leaving_Window in your application. You should claim Null_Reason_Code when passed to your application, otherwise the pointer will not change when the pointer is over the icon/workarea, see the examples for more. You should support the !Help application to help new users using your application, this is why I implemented a feature in Interface to make this easier. The following was for some reason not published in the Programmers Reference Manuals, but was in the pre-release disc version of the manuals. For an application to use interactive help, two WIMP messages are employed. One is used by the Help to request help, and the other is used by the application to return the help message. To request help, the Help application sends a message of the following form: block +16 &502 - indicates request for help +20 mouse x co-ordinate +24 mouse y co-ordinate +28 mouse button state +32 window handle (-1 if not over a window) +36 icon handle (-1 if not over an icon) The WIMP system will pass this message automatically to the task in charge of the appropriate window/icon. If the application receiving the message wishes to produce some help, it should respond with the following message: block +16 &503 +20 help message terminated by 0 This message can be sent to the Help application by using Wimp_SendHelp, which is provided by the Interface module (SWI &81687). The help text may contain any printable character codes. If the sequence |M is encountered then this will be treated as a line break and subsequent text will be printed on the next line in the window. If the text is too long for one line then it will be split at a word boundary (space character). The text should consist of simple complete English sentences, each starting on a new line and ending with a full stop. The sentences should usually be simple imperatives or information such as: Click SELECT to set the alarm. You are in Select mode. Click ADJUST to change to path edit mode. This is the icon for Edit. In general you need not mention menu entries, except when specific ones interact with pointer operations. As a general rule present information of interest to the beginner near the top, and expert tips or information lower down. You must use the terminology defined. For mouse operations you must use initial capitals (for example Click). The mouse buttons must be in capitals (for example SELECT), as must key names (for example ESC, RETURN, SHIFT, CONTROL, A, B, F1, COPY). miss out speedups and shortcuts - just provide enough to help a beginner without drowning them with information. Provide interactive help thoroughly - include the icon bar, and the workarea of all your windows. If no actions are possible in a window, just This window shows.... is better than nothing. You should assume a user knows: what a MENU key is how to navigate menu trees and choose entries what the icon bar is how to move/size/toggle/close windows, and so on what 'dragging an icon' means what 'filling in a field' (writable icon) means The keycode command should be placed in the icon that is activated by the keycode. It should be a decimal integer specifying the key. The up/down arrows, tab etc.. are dealt with. **************************** The SWI Calls ********************************* Wimp_BorderIcon (Interface_SlabButton) (SWI &81680) R1 = pointer to block R1 preserved Interrupts are not defined Fast interrupts are enabled Processor is in SVC mode SWI is not re-entrant The block contains the following on entry: R1+0 mouse x (screen coordinates - not window relative) R1+4 mouse y R1+8 buttons (depending on icon button type) R1+12 window handle R1+16 icon handle This call is used to update an icons border. It is typically called as a result of a Mouse_Click event, if the icon has a border type of 0 or 2 then the icon will slab inwards. The format of the validation string is described in the previous section. The application should the perform the task and then force the icon to normal status by calling Wimp_BorderIcon (SWI &81680) with R1+8 set to 0. The code to border icons and windows is outlined in the section Programming Interface. Note that the mouse coordinates specified in R1+0 and R1+4 are not used by the SWI and are only present to make the block compatible with a Mouse_Click event block. Wimp_BorderWindow (SWI &81681) None Wimp_BorderWindow (Interface_Render3dWindow) (SWI &81681) R1 = pointer to block R1 preserved Interrupts are not defined Fast interrupts are enabled Processor is in SVC mode SWI is not re-entrant The block contains the following on entry: R1+0 window handle R1+4 visible area minimum x coordinate R1+8 visible area minimum y coordinate R1+12 visible area maximum x coordinate R1+16 visible area maximum y coordinate R1+20 scroll x offset relative to work area origin R1+24 scroll y offset relative to work area origin R1+28 current graphics window minimum x coordinate R1+32 current graphics window minimum y coordinate R1+36 current graphics window maximum x coordinate R1+40 current graphics window maximum y coordinate This call is used to redraw the borders of icons in the window that are not up-to-date, this SWI is typically called during the redraw loop of a window. The SWI will update the window, drawing borders around any icons which have the b command specified in the validation string and are within the specified graphics window. The code to border icons and windows is outlined in the section Programming Interface. Wimp_BorderIcon (SWI &81680) None Wimp_ClaimInterface (Interface_Initialise) (SWI &81682) R0 = task handle R0 preserved Interrupts are not defined Fast interrupts are enabled Processor is in SVC mode SWI is not re-entrant This SWI allows your application to use pointers via the Interface module. This SWI should be called at the beginning of your program. If you don't use Wimp_ClaimInterface then your pointers will not be displayed. Wimp_ReleaseInterface (SWI &81683) None Wimp_ReleaseInterface (Interface_CloseDown) (SWI &81683) R0 = task handle R0 preserved Interrupts are not defined Fast interrupts are enabled Processor is in SVC mode SWI is not re-entrant This SWI stops your application from using pointers. When this SWI is called Interface Manager will erase any workarea pointers assigned to your application and free the memory. This should be called in your exit handler, also if an error occurs you should also call this SWI to stop other applications from gaining your pointers. Wimp_ClaimInterface (SWI &81682) None Wimp_SetWorkareaPointer (Interface_SetWorkareaPointer) (SWI &81684) R1 = pointer to block R1 preserved Interrupt status is undefined Fast interrupts are enabled Processor is in SVC mode SWI is not re-entrant The block contains the following on entry: R1+0 window handle R1+4 minimum x coordinate of bounding box R1+8 minimum y coordinate of bounding box R1+12 maximum x coordinate of bounding box R1+16 maximum y coordinate of bounding box R1+20 24 bytes of pointer data This specifies the pointer for an area of the window. The bounding box coordinates are given relative to the window's work area origin. R1+4 to R1+16 can be set to -1 to specify the whole of the window's work area. The pointer data at +20 to +44 contains the sprite name and any x, y offset, see validation strings for more information. Wimp_RemoveWorkareaPointer (SWI &81685) Wimp_PollPointer (SWI &81686) None Wimp_RemoveWorkareaPointer (Interface_RemoveWorkareaPointer) (SWI &81685) R0 = task handle R1 = pointer to block R0 preserved R1 preserved Interrupt status is undefined Fast interrupts are enabled Processor is in SVC mode SWI is not re-entrant The block contains the following on entry: R1+0 window handle R1+4 minimum x coordinate of bounding box R1+8 minimum y coordinate of bounding box R1+12 maximum x coordinate of bounding box R1+16 maximum y coordinate of bounding box This call removes a previously installed pointer from the list of active pointer areas for the specified window. When a window is deleted you should remove any pointers that were related to the window, otherwise these pointers may become active on any window which gains the same window handle in the future. The bounding box coordinates are given relative to the window's work area origin. R1+4 to R1+16 can be set to -1 to specify the whole of the window's work area. R1+4 to R1+16 may be set to 0 to remove all work area pointers assigned to the window. Wimp_SetWorkareaPointer (SWI &81684) Wimp_PollPointer (SWI &81686) None Wimp_PollPointer (Interface_Poll) (SWI &81686) R0 = Wimp_Poll reason code R2 = task handle R0 preserved R@ preserved Interrupt status is undefined Fast interrupts are enabled Processor is in SVC mode SWI not re-entrant This call checks to see if the pointer is up-to-date. If the pointer is not up-to-date it will change to the pointer specified in the icons validation string. If the pointer is not over an icon then the pointer will change according to the position on the window background. Note that wimp_poll reason codes 0 and 4 should not be masked out, otherwise the pointer will be out-of-date and will not function correctly. Wimp_SetWorkareaPointer (SWI &81684) Wimp_RemoveWorkareaPointer (SWI &81685) None Wimp_SendInformation (Interface_SendHelp) (SWI &81687) R1 = message block as returned from help application R1 preserved Interrupt status is undefined Fast interrupts are enabled Processor is in SVC mode SWI not re-entrant This call returns a help text message to the interactive help application. It should be called when a message with the number &502 is received and the pointer is over an icon. If there is a message in the icons validation string that the pointer is currently over then this will be sent to the help application. It is up to the applications programmer to take care of the help message when the pointer is over the icon on the icon bar or is over the window workarea. None None Wimp_PreProcessKey (Interface_PreProcessKey) (SWI &81688) R0 = event type R1 = event block R2 = task handle R0 = updated to new event type R1 = updated event block R2 = 0 if event was not dealt intercepted This call pre-processes the up, down, tab, shift-tab keys and any specified in a specific icons validation string using the command k<keycode>. The SWI will move icon, if neccessary or activate a button. This call should be called after the wimp_poll command, it will match the key to an icon and if neccessary modify your wimp poll block and event type. Wimp_BorderPlotIcon (Interface_Plot3dIcon) (SWI &81689) R0 = window state (either from wimp_update/redraw or from a wimp_getwindowstate) R1 = icon block as for Wimp_PlotIcon This call plots a border on a window like Wimp_PlotIcon. The icon block passed in R1 should contain a block as described for Wimp_PlotIcon in the PRMs. Wimp_BorderBoundingBox (Interface_BoundingBox) (SWI &8168A) R1 = icon block as for Wimp_PlotIcon R1 = updates icon block offset 0 min x 4 min y 8 max x 12 max y 16 border width 20 button slab state (1 = out, 0 = in) This call returns information about the icon block passed to it. If you wish to get the size of an icons box use Wimp_GetIconState and then pass the icon block returned to this function. Changes from version 1.32 this version has been fully re-written using the acorn aof assembler. border type has changed to z to avoid conflicts with risc-os 3 Interface_Plot3dIcon has been changed so the first parameter is a window state block instead of a window handle names has changed to interface_...., old names are still supported better redraw code to correct problems with multi-sync modes where the icons were not alligned correctly. Interface_BoundingBox now returns the state of the button new border types *command to allow changes in the slabbing colours.